﻿<?xml version="1.0" encoding="utf-8"?>
<developerSampleDocument
  xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
  xmlns:xlink="http://www.w3.org/1999/xlink">

  <!--
  <summary>
    <para>Optional summary abstract</para>
  </summary>
  -->

  <introduction>
    <!-- Uncomment this to generate an outline of the section and sub-section
         titles.  Specify a numeric value as the inner text to limit it to
         a specific number of sub-topics when creating the outline.  Specify
         zero (0) to limit it to top-level sections only.  -->
    <!-- <autoOutline /> -->
    
 </introduction>

  <!-- <procedure>Optional procedures.  See How To document for procedure layout example.</procedure> -->
  <!-- <requirements>Optional requirements section</requirements> -->
  <!-- <demonstrates>Optional info about what is demonstrated</demonstrates> -->
  <!-- <codeExample>Optional code example</codeExample> -->

  <!-- Add one or more top-level section elements.  These are collapsible.
       If using <autoOutline /> tag, add an address attribute to identify
       it so that it can be jumped to with a hyperlink. -->
  <section address="GettingStarted">
    <title>Getting Started</title>
    <content>
      <!-- Uncomment this to create a sub-section outline
      <autoOutline /> -->
      <list class="ordered">
	    <listItem>Download the latest release.</listItem>
		<listItem>Add a reference to VixCOMWrapper.dll to your project.</listItem>
		<listItem>Check the examples below or take a look at the sample application to learn how to use the library.</listItem>
	  </list>
	  
	  <alert class="note">
	  	<para>The VMware VIX API has to be installed in order for the library to work correctly. When a VMware product like Workstation, Server 1.x or 2.x is already installed, the VIX API will be available as well. In other cases, get the redistributable of the API from here: <externalLink><linkText>VMware VIX API homepage</linkText><linkUri>http://www.vmware.com/support/developer/vix-api/</linkUri></externalLink>.</para>
      </alert>
      <para/>
    </content>
  </section>
  
<section address="CodeExamples">
    <title>Code Examples</title>
    <content>
		<para>The following examples will give you a short introduction about the possibilities of the library.</para>

		<definitionTable>
		
		<definedTerm>Connecting to a VMware host</definedTerm>
		<definition>
			Here is an example of how to connect to a VMware host and getting an instance of the Host class.
			<code language="C#">
			VIX.Host hostObject = VIX.VixCOMWrapper.Instance.Connect(
			                                 VIX.Enums.VIX_SERVICEPROVIDER.VMWARE_VI_SERVER, 
			                                 "https://servername:8333/sdk",
			                                 0,
			                                 "Username",
			                                 "Password");
			</code>
			In the above example we are connecting to a VMware Server 2.x host. Remember to call hostObject.Disconnect() when you are done, otherwise VIX can't clean up handles etc.
			<para/>
		</definition>
		
		<definedTerm>Getting registered VMs</definedTerm>
		<definition>
			You can use the FindItems() function of the Host class to get the registered VMs.
			<code language="C#">
			List&lt;string&gt; vms = hostObject.FindItems(VIX.Enums.VIX_FIND.REGISTERED_VMS);
			</code>
			Similarily, if you want to get only the running VMs, pass VIX.Enums.VIX_FIND.RUNNING_VMS as parameter.
			<para/>
		</definition>
		
		<definedTerm>Starting a VM</definedTerm>
		<definition>
			You will need to connect to a host and retrieve a Host-object first, then you can call the OpenVM() function. You must pass the path to the .vmx file of the VM, in this case it is a VMware Server 2.x host, so we also need to specify the datastore (-> [standard] ).
			<code language="C#">
			VIX.VM vmObject = hostObject.OpenVM("[standard] VirtualMachine1.vmx");
			 
			vmObject.PowerOn(VIX.Enums.VIX_VMPOWEROP.NORMAL);
			</code>
			The PowerOn() function takes an enumeration as parameter, which specifies how the VM should be powered on. Check the documentation for details.
			<para/>
		</definition>
		
		<definedTerm>Running programs in the guest operating system</definedTerm>
		<definition>
			You can run any programs in the guest OS by using the RunProgramInGuest() function. Before calling this function, we need to establish an authentication context in the guest by calling LoginInGuest().
			<code language="C#">
			VIX.VM vmObject = hostObject.OpenVM("[standard] VirtualMachine1.vmx");
			 
			vmObject.LoginInGuest("Username", "Password", true);
			 
			vmObject.RunProgramInGuest(@"C:\Windows\system32\calc.exe", "", true, false, false);
			</code>
			<para/>
		</definition>
		
		<definedTerm>Getting basic information about a VM</definedTerm>
		<definition>
			With the GetProperties() function you can retrieve basic information about a VM, like the power-state, if VMware Tools are installed, etc.
			<code language="C#">
			VIX.VM vmObject = hostObject.OpenVM("[standard] VirtualMachine1.vmx");
			 
			List&lt;object&gt; result = vmx.GetProperties(
			new VIX.Enums.VIX_PROPERTY[] {     VIX.Enums.VIX_PROPERTY.VM_POWER_STATE, 
			                                          VIX.Enums.VIX_PROPERTY.VM_TOOLS_STATE, 
			                                          VIX.Enums.VIX_PROPERTY.VM_VMX_PATHNAME, 
			                                          VIX.Enums.VIX_PROPERTY.VM_SUPPORTED_FEATURES, 
			                                          VIX.Enums.VIX_PROPERTY.VM_MEMORY_SIZE, 
			                                          VIX.Enums.VIX_PROPERTY.VM_NUM_VCPUS, 
			                                          VIX.Enums.VIX_PROPERTY.VM_READ_ONLY }
			);
			MessageBox.Show("POWER_STATE: " + ( (VIX.Enums.VIX_POWERSTATE) result[0] ).ToString() );
			</code>
			
			Basically, you just pass the properties you want to retrieve in a VIX_PROPERTY array, the results will be stored in a list of objects. The first property requested matches the first value in the list and so on.
			<para/>
		</definition>
		</definitionTable>
    </content>
  </section>
  <relatedTopics>
    <!-- One or more of the following:
         - A local link
         - An external link
         - A code entity reference

    <link xlink:href="Other Topic's ID">Link text</link>
    <externalLink>
        <linkText>Link text</linkText>
        <linkAlternateText>Optional alternate link text</linkAlternateText>
        <linkUri>URI</linkUri>
    </externalLink>
    <codeEntityReference>API member ID</codeEntityReference>

    Examples:

    <link xlink:href="00e97994-e9e6-46e0-b420-5be86b2f8278">Some other topic</link>

    <externalLink>
        <linkText>SHFB on CodePlex</linkText>
        <linkAlternateText>Go to CodePlex</linkAlternateText>
        <linkUri>http://www.codeplex.com/SHFB</linkUri>
    </externalLink>

    <codeEntityReference>T:TestDoc.TestClass</codeEntityReference>
    <codeEntityReference>P:TestDoc.TestClass.SomeProperty</codeEntityReference>
    <codeEntityReference>M:TestDoc.TestClass.#ctor</codeEntityReference>
    <codeEntityReference>M:TestDoc.TestClass.#ctor(System.String,System.Int32)</codeEntityReference>
    <codeEntityReference>M:TestDoc.TestClass.ToString</codeEntityReference>
    <codeEntityReference>M:TestDoc.TestClass.FirstMethod</codeEntityReference>
    <codeEntityReference>M:TestDoc.TestClass.SecondMethod(System.Int32,System.String)</codeEntityReference>
    -->
  </relatedTopics>
</developerSampleDocument>
